home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Celestin Apprentice 5
/
Apprentice-Release5.iso
/
Source Code
/
Libraries
/
Bitmap Libraries 2.0
/
411 files
/
BitMapHelp
next >
Wrap
Text File
|
1996-03-10
|
41KB
|
1,335 lines
æKY CopyrightNoticeBitMapHelp
æC -----
BitMapHelp Copyright (c) 1996 by John Montbriand. All rights reserved.
æKY BitMap.h
BitMapHelp
BitMaps
æC -----
Routines for working with bitmap pointers.
BitMapHelp Copyright (c) 1996 by John Montbriand. All rights reserved.
storage managment for bitmaps:
NewBitMap -- create a new bitmap pointer
KillBitMap -- dispose of a bitmap pointer
DuplicateBitMap -- make a duplicate
flip and rotate routines:
RotateRight -- 90 degrees to the right
RotateLeft -- 90 degrees to the left
FlipVertical -- flip vertically
FlipHorizontal -- flip horizontally
RotateBitMap -- rotate to a particular angle
paint bucket and lasso routines:
PaintBucketBitMap -- paint bucket
LassoBitMap -- the lasso
special effects:
TraceBitMap -- trace the edges of a bitmap image
QuickDraw picture transfer functions:
PICTToBitMap -- convert a QuicDraw Picture to a bitmap pointer
BitMapToPICT -- convert a bitmap pointer to a QuicDraw Picture
logical operations:
BitMapAND -- logically AND raster data
BitMapOR -- logically OR raster data
BitMapXOR -- logically XOR raster data
BitMapNOT -- logically COMPLEMENT raster data
comparison:
EqualBitMaps -- compare two bitmaps for equality
pixel oriented functions:
BitMapTest -- test the value of a particular pixel
BitMapSet -- set a particular pixel to the value 1
BitMapClear -- set a particular pixel to the value 0
BitMapToggle -- invert a pixel returning it's new value
routines for drawing into bitmaps:
NewBMP -- called by WithBitMap to set up a grafport
DisposeBMP -- called by WithBitMap to dispose of a grafport
WithBitMap -- MACRO for drawing into bitmaps
routines for copying bitmap data:
PlotBitMap -- copy bitmap data to the current grafport
æKY NewBitMap
æFc BitMap.h
æMM
æD BitMap* NewBitMap(short width, short height);
æDT BitMap *bits = NewBitMap((short) width, (short) height);
æT Function
æC -----
for creating a new bitmap pointer.
arguments:
width the width of the requested bitmap
height the height of the requested bitmap
return value:
a pointer to a Bitmap data structure.
if an error occurs, NULL is returned.
description:
NewBitMap creates a new bitmap pointer with the requested
dimensions. The raster data is initialized to zeros, and if
there is not enough memory to allocate the bitmap, NewBitMap
will return NULL.
example application:
The following creates a new bitmap pointer 100 pixels wide
and 200 pixels tall.
{ BitMap *the_bits;
the_bits = NewBitMap(100, 200);
...
notes:
You can call DisposePtr to dispose of a bitmap pointer created by
NewBitMap. The routine KillBitMap calls DisposePtr.
æKY KillBitMap
æFc BitMap.h
æMM
æD void KillBitMap(BitMap* bits);
æDT KillBitMap((BitMap*) bits);
æT Procedure
æC -----
to dispose of the storage occupied by a bitmap pointer.
arguments:
bits a bitmap pointer
return value:
none.
description:
KillBitMap disposes of a bitmap pointer allocated by one of:
NewMacPaintBitMap, NewBitMap, RotateRight, RotateLeft, FlipVertical,
FlipHorizontal, RotateBitMap, DuplicateBitMap, PaintBucketBitMap,
LassoBitMap, PICTToBitMap, BitMapAND, BitMapOR, BitMapXOR, or BitMapNOT.
It's your general all purpose bitmap pointer disposal function.
example application:
The following creates a new bitmap handle 100 pixels wide
and 200 pixels tall and then disposes of it by calling KillBitMap.
{ BitMap *the_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
KillBitMap(the_bits);
}
notes:
KillBitMap simply calls DisposePtr.
æKY RotateRight
æFc BitMap.h
æMM
æD BitMap* RotateRight(BitMap* bits);
æDT BitMap *round_bits = RotateRight((BitMap*) bits);
æT Function
æC -----
to rotate a bitmap 90 degrees to the right.
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated 90 degrees
to the right.
if an error occurs, RotateRight will return the value NULL.
description:
RotateRight creates a new bitmap containing the image
stored in the parameter bitmap pointer rotated 90 degrees
to the right. The resulting bitmap is appropriately sized:
i.e. if the source bitmap is 100 pixels wide and 200 pixels tall,
then the result bitmap pointer will be 200 pixels wide and 100
pixels tall.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 90 degrees to the right
before copying the image to the current grafport.
{ BitMap *the_bits;
BitMap *rotated_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
rotated_bits = RotateRight(the_bits);
if (rotated_bits != NULL) {
bounds = (*rotated_bits)->bounds;
PlotMap(rotated_bits, 0, 0, srcCopy);
KillBitMap(rotated_bits);
}
KillBitMap(the_bits);
}
notes:
RotateRight takes advantage of certain addressing and indexing
possibilities offered by the arrangement of the raster data
in memory. It is faster than calling RotateBitMap and specifying
a 90 degree angle.
æKY RotateLeft
æFc BitMap.h
æMM
æD BitMap* RotateLeft(BitMap* bits);
æDT BitMap *left_bits = RotateLeft((BitMap*) bits);
æT Function
æC -----
to rotate a bitmap image 90 degrees to the left.
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated 90 degrees
to the left.
if an error occurs, RotateLeft will return the value NULL.
description:
RotateLeft creates a new bitmap containing the image
stored in the parameter bitmap pointer rotated 90 degrees
to the left. The resulting bitmap is appropriately sized:
i.e. if the source bitmap is 100 pixels wide and 200 pixels tall,
then the result bitmap pointer will be 200 pixels wide and 100
pixels tall.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 90 degrees to the left
before copying the image to the current grafport.
{ BitMap *the_bits;
BitMap *rotated_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
rotated_bits = RotateLeft(the_bits);
if (rotated_bits != NULL) {
bounds = (*rotated_bits)->bounds;
PlotMap(rotated_bits, 0, 0, srcCopy);
KillBitMap(rotated_bits);
}
KillBitMap(the_bits);
}
notes:
RotateLeft takes advantage of certain addressing and indexing
possibilities offered by the arrangement of the raster data
in memory. It is faster than calling RotateBitMap and specifying
a -90 degree angle.
æKY FlipVertical
æFc BitMap.h
æMM
æD BitMap* FlipVertical(BitMap* bits);
æDT BitMap *vertical_bits = FlipVertical((BitMap*) bits);
æT Function
æC -----
to flip a bitmap vertically.
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter flipped upside down.
if an error occurs, FlipVertical will return the value NULL.
description:
FlipVertical creates a new bitmap containing the image
stored in the parameter bitmap pointer flipped upside
down. The resulting bitmap will be the same size as
the original image.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap flipped upside down before
copying the new flipped image to the current grafport.
{ BitMap *the_bits;
BitMap *flippin_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
flippin_bits = FlipVertical(the_bits);
if (flippin_bits != NULL) {
bounds = (*flippin_bits)->bounds;
PlotMap(flippin_bits, 0, 0, srcCopy);
KillBitMap(flippin_bits);
}
KillBitMap(the_bits);
}
notes:
flippin!
æKY FlipHorizontal
æFc BitMap.h
æMM
æD BitMap* FlipHorizontal(BitMap* bits);
æDT BitMap *horizontal_bits = FlipHorizontal((BitMap*) bits);
æT Function
æC -----
to flip a bitmap horizontally.
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter flipped horizontally.
if an error occurs, FlipVertical will return the value NULL.
description:
FlipHorizontal creates a new bitmap containing the image
stored in the parameter bitmap pointer flipped horizontally.
The resulting bitmap will be the same size as the original image.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap flipped horizontally before
copying the new flipped image to the current grafport.
{ BitMap *the_bits;
BitMap *flippin_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
flippin_bits = FlipHorizontal(the_bits);
if (flippin_bits != NULL) {
bounds = (*flippin_bits)->bounds;
PlotMap(flippin_bits, 0, 0, srcCopy);
KillBitMap(flippin_bits);
}
KillBitMap(the_bits);
}
notes:
none.
æKY RotateBitMap
æFc BitMap.h
æMM
æD BitMap* RotateBitMap(BitMap* bits, short cx, short cy, float angle);
æDT BitMap *round_bits = RotateBitMap((BitMap*) bits, (short) cx, (short) cy, (float) angle);
æT Function
æC -----
to rotate a bitmap to a specific angle.
arguments:
bits a bitmap pointer
cx the horizontal center of rotation
cy the vertical center of rotation
angle the angle (in degrees) to rotate the image. both positive
and negative values are ok. This is a floating point number.
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated around the center
cx and cy angle degrees.
if an error occurs, RotateBitMap will return the value NULL.
description:
RotateBitMap creates a new bitmap containing the image from
the parameter bitmap pointer rotated angle degrees about the
center (cx, cy). The resultant bitmap will have the same dimensions
as the parameter bitmap regardless of the angle specified.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 35.5 degrees to the right
before copying the rotated image to the current grafport.
{ BitMap *the_bits;
BitMap *round_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
round_bits = RotateBitMap(the_bits, 50, 100, 35.5);
if (round_bits != NULL) {
bounds = (*round_bits)->bounds;
PlotMap(round_bits, 0, 0, srcCopy);
KillBitMap(round_bits);
}
KillBitMap(the_bits);
}
notes:
The 68k implementation of RotateBitMap has a speedy implementation
built on top of the fixed math routines. For more information
about fixed math refer to the Mathematical and Logical Utilities
chapter of Inside Macintosh: Operating System Utilities.
æKY DuplicateBitMap
æFc BitMap.h
æMM
æD BitMap* DuplicateBitMap(BitMap* bits);
æDT BitMap *bitmap_copy = DuplicateBitMap((BitMap*) bits);
æT Function
æC -----
to make a copy of a bitmap.
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing an
exact duplicate of the bitmap parameter.
if an error occurs, DuplicateBitMap will return the value NULL.
description:
DuplicateBitMap creates a copy of the bitmap parameter.
example application:
In this example, we make a new bitmap, duplicate it, and then
dispose of the resulting bitmaps.
{ BitMap *the_bits;
BitMap *other_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
other_bits = DuplicateBitMap(the_bits);
if (other_bits != NULL) {
KillBitMap(other_bits);
}
KillBitMap(the_bits);
}
notes:
none.
æKY PaintBucketBitMap
æFc BitMap.h
æMM
æD BitMap* PaintBucketBitMap(BitMap* bits, short h, short v);
æDT BitMap *painted_bits = PaintBucketBitMap((BitMap*) bits, (short) h, (short) v);
æT Function
æC -----
to create a paint bucket type mask for a bitmap.
arguments:
bits a bitmap pointer
h the horizontal position to start painting
v the vertical position to start painting
return value:
a newly created bitmap pointer containing an ones in every
pixel where paint would not leak out starting from the point
(h, v).
if an error occurs, PaintBucketBitMap will return the value NULL.
description:
PaintBucketBitMap works like the paint bucket tool found in
most graphical applications. It calls the routine SeedFill
and to fill in the image information in the resulting bitmap
pointer.
example application:
In this example, we make a new bitmap and create a mask bitmap
using the PaintBucketBitMap routine starting at the point (50,50).
{ BitMap *the_bits;
BitMap *paint_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here, we would normally draw something in the bitmap */
paint_bits = PaintBucketBitMap(the_bits, 50, 50);
if (paint_bits != NULL) {
KillBitMap(paint_bits);
}
KillBitMap(the_bits);
}
notes:
PaintBucketBitMap calls SeedFill. For further information about
SeedFill refer to page 3-109 in the QuickDraw Drawing chapter of
Inside Macintosh: Imaging With QuickDraw.
æKY LassoBitMap
æFc BitMap.h
æMM
æD BitMap* LassoBitMap(BitMap* bits);
æDT BitMap *lassod_bits = LassoBitMap((BitMap*) bits);
æT Function
æC -----
to create a lasso'd mask of a bitmap.
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing an ones in every
pixel where paint would not leak in from the edges of the
bitmap.
if an error occurs, LassoBitMap will return the value NULL.
description:
LassoBitMap works like the lasso bucket tool found in
most graphical applications. It calls the routine CalcMask
and to fill in the image information in the resulting bitmap
pointer.
example application:
In this example, we make a new bitmap and create a mask bitmap
using the LassoBitMap routine.
{ BitMap *the_bits;
BitMap *paint_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here, we would normally draw something in the bitmap */
paint_bits = LassoBitMap(the_bits);
if (paint_bits != NULL) {
KillBitMap(paint_bits);
}
KillBitMap(the_bits);
}
notes:
LassoBitMap calls CalcMask. For further information about
CalcMask refer to page 3-111 in the QuickDraw Drawing chapter of
Inside Macintosh: Imaging With QuickDraw.
æKY TraceBitMap
æFc BitMap.h
æMM
æD BitMap* TraceBitMap(BitMap* bits);
æDT BitMap *traced_bits = TraceBitMap((BitMap*) bits);
æT Function
æC -----
to create a traced edges version of the bitmap.
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing containing the original
image with the edges traced.
if an error occurs, TraceBitMap will return the value NULL.
description:
TraceBitMap performs the 'trace edges' command found in
many graphical applications returning a new bitmap
containing the traced image..
example application:
In this example, we make a new bitmap and create a new bitmap
containing the traced image.
{ BitMap *the_bits;
BitMap *traced_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here, we would normally draw something in the bitmap */
traced_bits = TraceBitMap(the_bits);
if (traced_bits != NULL) {
KillBitMap(traced_bits);
}
KillBitMap(the_bits);
}
notes:
none.
æKY EqualBitMaps
æFc BitMap.h
æMM
æD Boolean EqualBitMaps(BitMap* a, BitMap* b);
æDT Boolean is_equal = EqualBitMaps((BitMap*) a, (BitMap*) b);
æT Function
æC -----
compares two bitmaps for equality.
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
true or false.
description:
returns true if the two bitmaps are the same size and
contain the same image content. returns false if either
bitmap is NULL.
example application:
In this example, we make a new bitmap and create a two bitmaps
and compare them by calling EqualBitMaps.
{ BitMap *the_bits;
BitMap *other_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
other_bits = TraceBitMap(the_bits);
if (other_bits != NULL) {
/* here, we would normally draw something in the bitmaps */
if (EqualBitMaps(other_bits, the_bits)) {
/* they're the same *blink* */
}
KillBitMap(other_bits);
}
KillBitMap(the_bits);
}
notes:
EqualBitMaps takes into account that either bitmap may have
different rowBytes values, and the possibility that garbage
values may be stored in the unused bits off to the right
of the boundary rectangle.
æKY PICTToBitMap
æFc BitMap.h
æMM
æD BitMap* PICTToBitMap(PicHandle pic);
æDT BitMap *picture_bits = PICTToBitMap((PicHandle) pic);
æT Function
æC -----
to convert a QuickDraw Picture into a bitmap pointer.
arguments:
pic a handle to a QuickDraw picture
return value:
a newly created bitmap pointer containing a black and white
representation of the image drawn by the quickdraw picture
parameter.
if an error occurs, PICTToBitMap will return the value NULL.
description:
PICTToBitMap creates a new bitmap pointer the using the size
information provided in the QuickDraw picture handle parameter
and draws the picture in the bitmap before returning the bitmap.
example application:
In this example, we call GetPicture to retrieve a picture from
a resource file and then we convert it to a bitmap by calling
the routine PICTToBitMap.
{ PicHandle the_picture;
BitMap *the_bits;
the_picture = GetPicture(128);
if (the_picture != NULL) {
the_bits = PICTToBitMap(the_picture);
if (the_bits != NULL) {
/* at this point, the the_bits contains the picture */
KillBitMap(the_bits);
}
}
notes:
none.
æKY BitMapToPICT
æFc BitMap.h
æMM
æD PicHandle BitMapToPICT(BitMap* bits);
æDT PicHandle the_picture = BitMapToPICT((BitMap*) bits);
æT Function
æC -----
to convert a bitmap pointer into a QuickDraw Picture.
arguments:
bits a bitmap pointer
return value:
a handle to a QuickDraw picture.
if an error occurs, the picture's picFrame will be
an empty rectangle.
description:
BitMapToPICT returns a QuickDraw picture that will draw the
image stored in the bitmap. BitMapToPICT is the inverse
of PICTToBitMap.
example application:
In this example, we create a bitmap and convert it into a QuickDraw
picture.
{ PicHandle the_picture;
BitMap *the_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
the_picture = BitMapToPICT(the_bits);
KillBitMap(the_bits);
}
notes:
QuickDraw pictures are a good way to store image data.
æKY BitMapAND
æFc BitMap.h
æMM
æD BitMap* BitMapAND(BitMap* a, BitMap* b);
æDT BitMap *anded_bits = BitMapAND((BitMap*) a, (BitMap*) b);
æT Function
æC -----
to logically AND the raster data from two bitmaps.
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of ANDing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
BitMapAND logically ANDs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and AND them together creating
a third bitmap.
{ BitMap *a=NULL, *b=NULL, *c=NULL;
a = NewBitMap(100, 100);
if (a == NULL) goto my_error_handler;
b = NewBitMap(100, 100);
if (b == NULL) goto my_error_handler;
c = BitMapAND(a, b);
if (c == NULL) goto my_error_handler;
/* at this point, c contains the result of logically ANDing
the bitmaps a and b */
my_error_handler:
if (a != NULL) KillBitMap(a);
if (b != NULL) KillBitMap(b);
if (c != NULL) KillBitMap(c);
}
notes:
useful for calculating the intersection of two sets of bits.
æKY BitMapOR
æFc BitMap.h
æMM
æD BitMap* BitMapOR(BitMap* a, BitMap* b);
æDT BitMap *ored_bits = BitMapOR((BitMap*) a, (BitMap*) b);
æT Function
æC -----
to logically OR the raster data from two bitmaps.
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of ORing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
BitMapOR logically ORs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and OR them together creating
a third bitmap.
{ BitMap *a=NULL, *b=NULL, *c=NULL;
a = NewBitMap(100, 100);
if (a == NULL) goto my_error_handler;
b = NewBitMap(100, 100);
if (b == NULL) goto my_error_handler;
c = BitMapOR(a, b);
if (c == NULL) goto my_error_handler;
/* at this point, c contains the result of logically ORing
the bitmaps a and b */
my_error_handler:
if (a != NULL) KillBitMap(a);
if (b != NULL) KillBitMap(b);
if (c != NULL) KillBitMap(c);
}
notes:
useful for calculating the union of two sets of bits.
æKY BitMapXOR
æFc BitMap.h
æMM
æD BitMap* BitMapXOR(BitMap* a, BitMap* b);
æDT BitMap *xored_bits = BitMapXOR((BitMap*) a, (BitMap*) b);
æT Function
æC -----
to logically XOR the raster data from two bitmaps.
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of XORing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
BitMapXOR logically XORs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and XOR them together creating
a third bitmap.
{ BitMap *a=NULL, *b=NULL, *c=NULL;
a = NewBitMap(100, 100);
if (a == NULL) goto my_error_handler;
b = NewBitMap(100, 100);
if (b == NULL) goto my_error_handler;
c = BitMapXOR(a, b);
if (c == NULL) goto my_error_handler;
/* at this point, c contains the result of logically XORing
the bitmaps a and b */
my_error_handler:
if (a != NULL) KillBitMap(a);
if (b != NULL) KillBitMap(b);
if (c != NULL) KillBitMap(c);
}
notes:
useful for calculating the difference of two sets of bits.
æKY BitMapNOT
æFc BitMap.h
æMM
æD BitMap* BitMapNOT(BitMap* a);
æDT BitMap *angry_bits = BitMapNOT((BitMap*) a);
æT Function
æC -----
complement a bitmap.
arguments:
a a bitmap pointer
return value:
a bitmap pointer containing the logical result of complementing the
raster data from bitmap a.
if an error occurs, NULL is returned.
description:
BitMapNOT returns a new bitmap pointer containing the inverse
of the raster image contained in the bitmap pointer a.
example application:
In this example, we create a bitmap and it's complement.
{ BitMap *a=NULL, *b=NULL;
a = NewBitMap(100, 100);
if (a == NULL) goto my_error_handler;
b = BitMapNOT(a);
if (b == NULL) goto my_error_handler;
/* at this point, b contains the compliment of a */
my_error_handler:
if (a != NULL) KillBitMap(a);
if (b != NULL) KillBitMap(b);
}
notes:
useful for calculating the complement of a set of bits.
æKY BitMapTest
æFc BitMap.h
æD Boolean BitMapTest(BitMap* bits, short h, short v);
æDT Boolean pixel_value = BitMapTest((BitMap*) bits, (short) h, (short) v);
æT Function
æC -----
test the value of a particular pixel in a bitmap.
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to test
v the vertical position of the pixel to test
return value:
true if the pixel is 1, false if the pixel is 0.
description:
BitMapTest tests the value of the pixel at the location (h,v)
returning true if the pixel is 1, and false if the pixel
is zero.
example application:
In this example, we create a bitmap and test the pixel
located at (25, 32).
{ BitMap *bits=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
....
if (BitMapTest(bits, 25, 32)) {
/* the pixel is 1 */
} else {
/* the pixel is 0 */
}
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
attempting to test a point outside of the bitmap's bounds
will produce unpredictable results.
æKY BitMapSet
æFc BitMap.h
æD void BitMapSet(BitMap* bits, short h, short v);
æDT BitMapSet((BitMap*) bits, (short) h, (short) v);
æT Procedure
æC -----
set the value of a particular pixel.
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
none.
description:
BitMapSet sets the value of the pixel at the location (h,v) to 1.
example application:
In this example, we create a bitmap and set the pixel
located at (25, 32) to the value 1.
{ BitMap *bits=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
....
BitMapSet(bits, 25, 32);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
attempting to set a point outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
æKY BitMapClear
æFc BitMap.h
æD void BitMapClear(BitMap* bits, short h, short v);
æDT BitMapClear((BitMap*) bits, (short) h, (short) v);
æT Procedure
æC -----
clear the value of a particular pixel.
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
none.
description:
BitMapClear clears the value of the pixel at the location (h,v)
to 0.
example application:
In this example, we create a bitmap and set the pixel
located at (25, 32) to the value 0.
{ BitMap *bits=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
....
BitMapClear(bits, 25, 32);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
attempting to clear a point outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
æKY BitMapToggle
æFc BitMap.h
æD Boolean BitMapToggle(BitMap* bits, short h, short v);
æDT Boolean new_value = BitMapToggle((BitMap*) bits, (short) h, (short) v);
æT Procedure
æC -----
invert the value of a particular pixel returning it's new value.
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
a boolean value indicating the state of the pixel
after the toggle operation. i.e. if the pixel is
set to the value 1, true is returned. If the pixel
is set to the value 0, false is returned.
description:
BitMapToggle inverts the value of the pixel at the location (h,v)
returning true if the pixel is set to 1 or false if the pixel
is set to 0.
example application:
In this example, we create a bitmap and invert the pixel
located at (25, 32).
{ BitMap *bits=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
....
BitMapToggle(bits, 25, 32);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
attempting to toggle a point outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
æKY NewBMP
æFc BitMap.h
æMM
æD BitMapPort* NewBMP(BitMap* bits);
æDT BitMapPort *bmp = NewBMP((BitMap*) bits);
æT Function
æC -----
set up a drawing environment for drawing into a bitmap.
arguments:
bits a bitmap pointer
return value:
a pointer to a BitMapPort data structure.
if an error occurs, NULL is returned.
description:
NewBMP is called by the WithBitMap macro and you should
never have to call it directly yourself. What it does is
it saves the original grafport, and creates a new grafport
suitable for drawing into the bitmap. NewBMP should be
followed by a call to DisposeBMP which will restore the
original grafport, unlock the bitmap, and dispose of the
new grafport.
example application:
In this example, we create a bitmap and use the NewBMP to make
a grafport. Then we draw into it and call DisposeBMP to deallocate
the grafport.
{ BitMap *bits=NULL;
BitMapPort *bmp=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
bmp = NewBMP(bits);
if (bmp == NULL) goto my_error_handler;
/* after NewBMP, the grafport is set to draw into the bitmap */
MoveTo(10,10);
LineTo(20,20);
DrawString("\pHello World");
my_error_handler:
if (bmp != NULL) DisposeBMP(bmp);
if (bits != NULL) KillBitMap(bits);
}
notes:
if NewBMP returns a pointer to a BitMapPort, then you must
dispose of that pointer with a call to DisposeBMP.
æKY DisposeBMP
æFc BitMap.h
æMM
æD void DisposeBMP(BitMapPort* bmp);
æDT DisposeBMP((BitMapPort*) bmp);
æT Procedure
æC -----
dispose of a drawing enviroment created by NewBMP and restore the previous
drawing environment.
arguments:
bmp a pointer to a BitMapPort structure allocated by NewBMP
return value:
none.
description:
DisposeBMP restores the original grafport and, deallocates
the grafport allocated for drawing into the bitmap.
The macro WithBitMap calls this routine automatically and you will
not normally have to call it directly.
example application:
see the example in NewBMP.
notes:
none.
æKY WithBitMap
æFc BitMap.h
æMM
æD #define WithBitMap(bits, bmp)
æDT WithBitMap(((BitMap*) bits), ((BitMapPort*) bmp)) { statement... }
æT Macro
æC -----
execute a statement while the drawing environment is set up to
draw into the bitmap.
arguments:
bits a bitmap pointer
bmp a variable you have declared of type BitMapPort*
return value:
not applicable
description:
WithBitMap is a macro facility that sets up the drawing
environment such that any drawing commands in the statement
following the macro instantiation will draw into the bitmap
provided as the first parameter.
example application:
In this example, we create a bitmap and use the WithBitMap
macro to do some drawing in it.
{ BitMap *bits=NULL;
BitMapPort *bmp;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
WithBitMap(bits, bmp) {
MoveTo(10,10);
LineTo(20,20);
TextFont(geneva);
TextSize(12);
DrawString("\pHello World");
}
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
WithBitMap macros can be nested, however if you do this you must
provide a different variable of type (BitMapPort *) for each
instantiation.
æKY PlotBitMap
æFc BitMap.h
æMM
æD void PlotBitMap(BitMap* bits, short h, short v);
æDT PlotBitMap((BitMap*) bits, (short) h, (short) v);
æT Procedure
æC -----
for creating a new bitmap pointer.
arguments:
bits a bitmap pointer
h the horizontal location where the bitmap is drawn
v the horizontal location where the bitmap is drawn
mode transfer mode passed to copybits
return value:
none.
description:
PlotBitMap provides a simple interface for drawing a bitmap in
the current grafport. The bitmap is drawn with the top left corner
aligned with the point (h,v) using the indicated transfer mode.
In this example, we create a bitmap and use the WithBitMap
macro to do some drawing in it, and then we copy the result
to the current grafport at the location (75, 23) using the
PlotBitMap routine.
{ BitMap *bits=NULL;
BitMapPort *bmp;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
WithBitMap(bits, bmp) {
MoveTo(10,10);
TextFont(geneva);
TextSize(12);
DrawString("\pHello World");
}
PlotBitMap(bits, 75, 23, srcCopy);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
PlotBitMap calls CopyBits.
æKY BitMapPort
æFc BitMap.h
æT structure
æD typedef struct {
GrafPort gp; /* the grafport record for drawing into the bitmap */
GrafPtr gpsave; /* saved grafport for later restoration */
BitMap* bits; /* the bitmap handle */
} BitMapPort;
æC -----
BitMapPort data structure managed by the routines NewBMP
and DisposeBMP. You should never have to access the fields of this
record directly as it's all taken care of by NewBMP and DisposeBMP.
